Crate kurbo

2D geometry, with a focus on curves.

The kurbo library contains data structures and algorithms for curves and vector paths. It was designed to serve the needs of 2D graphics applications, but it is intended to be general enough to be useful for other applications.

Kurbo is designed to be used by Piet, a crate for drawing 2D graphics, and is in turn used by Druid, a cross-platform GUI toolkit.

Examples

Basic UI-style geometry:

use kurbo::{Insets, Point, Rect, Size, Vec2};

let pt = Point::new(10.0, 10.0);
let vector = Vec2::new(5.0, -5.0);
let pt2 = pt + vector;
assert_eq!(pt2, Point::new(15.0, 5.0));

let rect = Rect::from_points(pt, pt2);
assert_eq!(rect, Rect::from_origin_size((10.0, 5.0), (5.0, 5.0)));

let insets = Insets::uniform(1.0);
let inset_rect = rect - insets;
assert_eq!(inset_rect.size(), Size::new(3.0, 3.0));

Finding the closest position on a Shape’s perimeter to a Point:

use kurbo::{Circle, ParamCurve, ParamCurveNearest, Point, Shape};

const DESIRED_ACCURACY: f64 = 0.1;

/// Given a shape and a point, returns the closest position on the shape's
/// perimeter, or `None` if the shape is malformed.
fn closest_perimeter_point(shape: impl Shape, pt: Point) -> Option<Point> {
    let mut best: Option<(Point, f64)> = None;
    for segment in shape.path_segments(DESIRED_ACCURACY) {
        let nearest = segment.nearest(pt, DESIRED_ACCURACY);
        if best.map(|(_, best_d)| nearest.distance_sq < best_d).unwrap_or(true) {
            best = Some((segment.eval(nearest.t), nearest.distance_sq))
        }
    }
    best.map(|(point, _)| point)
}

let circle = Circle::new((5.0, 5.0), 5.0);
let hit_point = Point::new(5.0, -2.0);
let expectation = Point::new(5.0, 0.0);
let hit = closest_perimeter_point(circle, hit_point).unwrap();
assert!(hit.distance(expectation) <= DESIRED_ACCURACY);

Features

This crate either uses the standard library or the libm crate for math functionality. The std feature is enabled by default, but can be disabled, as long as the libm feature is enabled. This is useful for no_std environments. However, note that the libm crate is not as efficient as the standard library, and that this crate still uses the alloc crate regardless.

Modules

• common
  Common mathematical operations
• offset
  Computation of offset curves of cubic Béziers, based on a curve fitting approach.
• simplify
  Simplification of a Bézier path.

Structs

• Affine
  A 2D affine transform.
• Arc
  A single arc segment.
• BezPath
  A Bézier path.
• Circle
  A circle.
• CircleSegment
  A segment of a circle.
• ConstPoint
  A trivial “curve” that is just a constant.
• CubicBez
  A single cubic Bézier segment.
• CubicBezIter
  An iterator for cubic beziers.
• CurveFitSample
  A sample point of a curve for fitting.
• Ellipse
  An ellipse.
• Insets
  Insets from the edges of a rectangle.
• Line
  A single line.
• LineIntersection
  An intersection of a Line and a PathSeg.
• MinDistance
  The minimum distance between two Bézier curves.
• Nearest
  The nearest position on a curve to some point.
• PathSegIter
  An iterator for path segments.
• Point
  A 2D point.
• QuadBez
  A single quadratic Bézier segment.
• QuadBezIter
  An iterator for quadratic beziers.
• QuadSpline
  A quadratic Bézier spline in B-spline format.
• Rect
  A rectangle.
• RoundedRect
  A rectangle with equally rounded corners.
• RoundedRectRadii
  Radii for each corner of a rounded rectangle.
• Segments
  An iterator that transforms path elements to path segments.
• Size
  A 2D size.
• SvgArc
  A single SVG arc segment.
• TranslateScale
  A transformation including scaling and translation.
• Vec2
  A 2D vector.

Enums

• PathEl
  The element of a Bézier path.
• PathSeg
  A segment of a Bézier path.
• SvgParseError
  An error which can be returned when parsing an SVG.

Constants

• DEFAULT_ACCURACY
  A default value for methods that take an ‘accuracy’ argument.
• MAX_EXTREMA
  The maximum number of extrema that can be reported in the ParamCurveExtrema trait.

Traits

• ParamCurve
  A curve parametrized by a scalar.
• ParamCurveArclen
  A parametrized curve that can have its arc length measured.
• ParamCurveArea
  A parametrized curve that can have its signed area measured.
• ParamCurveCurvature
  A parametrized curve that reports its curvature.
• ParamCurveDeriv
  A differentiable parametrized curve.
• ParamCurveExtrema
  A parametrized curve that reports its extrema.
• ParamCurveFit
  The source curve for curve fitting.
• ParamCurveNearest
  A parametrized curve that reports the nearest point.
• Shape
  A generic trait for open and closed shapes.

Functions

• cubics_to_quadratic_splines
  Convert multiple cubic Bézier curves to quadratic splines.
• fit_to_bezpath
  Generate a Bézier path that fits the source curve.
• fit_to_bezpath_opt
  Generate a highly optimized Bézier path that fits the source curve.
• fit_to_cubic
  Fit a single cubic to a range of the source curve.
• flatten
  Flatten the path, invoking the callback repeatedly.
• segments
  Transform an iterator over path elements into one over path segments.